* --------------------
* LTVT Script Commands
* --------------------
(Rev. 08 Nov 2010)
  
This document describes the syntax of the scripts that can be used to automate operations in LTVT.  Script operations work exactly the same as, and can be used as a supplement to, manually performing the corresponding data input operations and/or mouse clicks.

In LTVT_v0_21_5x1.exe, script text is entered and run via the "Script text" box on the "Files...Run script..." form. Script text can be efficiently added to the box from a text file by highlighting the portion of interest, copying it to the clipboard with the CTRL-C keystroke combination, positioning the cursor in the LTVT "Script text" box and pasting the text with CTRL-V.  Once in the box, the script can be edited as desired.

Within the script, blank lines and lines with a leading asterisk are treated as comments, and are ignored; but there is no mechanism for adding comments within or at the end of command lines.

Valid script lines consist of commands drawn from the following list which correspond to the controls found in the Main Screen plus a few additional operations. 

Commands are the first item on each command line.  Additional parameters, if any, are separated by commas.  

All parameters after the command, whether numeric or not, are regarded as text strings, but need be delimited by double quotes (") only if they themselves contain commas.  If a decimal point needs to be specified in a numeric string it must be represented by the full stop/period symbol (.).

Commands are converted to upper case before being processed, making the syntax case insensitive. As the script is run each command line is echoed to a separate memo box, followed by an error message if the command cannot be found in the following list.
  
For more information on LTVT see:  http://ltvt.wikispaces.com/


==LTVT SCRIPT SYNTAX BY CATEGORY==

* ---------------------------------------
* Enter data into main screen input boxes
* ---------------------------------------

Date, YYYY, MM, DD
Time, HH, MM, SS
SubObserverPoint, Lon, Lat
SubSolarPoint, Lon, Lat 
MinSize, nnn
Gamma, nnn
Zoom, nnn
Rot, nnn
Grid, nnn

* ---------------------------
* Set main screen check boxes
* ---------------------------

DisplayIn3D_on
DisplayIn3D_off
DrawCircles_on
DrawCircles_off
MarkCenter_on
MarkCenter_off


* -------------------------------
* Click main screen radio buttons
* -------------------------------

* radio buttons in the Geometry panel

DemNorm
DemHi
DemLo
DemConst

* radio buttons in the Moon Display panel

Texture1
Texture2
Texture3
UserPhoto
LTO


* --------------------------------
* Click main screen action buttons
* --------------------------------

CurrentUT
Location, Lon, Lat, Elev[m] * bypasses dialog if Lon/Lat supplied; Elev=0 assumed if omitted
ComputeGeometry
Label
Dots
Texture
DEM
OverlayDots
Reset
SaveImage, filename * bypasses dialog if file name is provided -- see note below
Predict
FindPhotos


* -------------------
* Off-screen commands
* -------------------

ShowEarth  * equivalent to "Tools...Show Earth viewed from Moon"

* the following are equivalent to setting parameters in the (observer) "Location" button dialog

Geocentric_on  * for ComputeGeometry
Geocentric_off * for ComputeGeometry

* following are equivalent to actions from "Tools...GoTo..." form
* if the Radius parameter is omitted, the Moon's radius will be assumed
* if other parameters are omitted, dialog is invoked

GotoLonLat, Lon, Lat, Radius[km]  * equivalent to clicking "Center On" button 
GotoLonLatAerial, Lon, Lat, Radius[km] * equivalent to clicking "Aerial View" button
GotoXY, xi, eta * equivalent to selecting "By X-Y position" then clicking "Center On" button

MarkLonLat, Lon, Lat, Radius[km] * equivalent to clicking "Mark" button
MarkXY, xi, eta * equivalent to selecting "By X-Y position" then clicking "Mark" button



* -----
* Notes
* -----

SaveImage :  If the "filename" parameter is omitted, this command is equivalent to clicking the "Save Image" button in the LTVT main screen and will produce a normal windows dialog for specifying the location and name under which the current screen image should be saved, and a warning if the file already exists.  If the "filename" parameter is specified, the image is saved as directed with no overwrite warning. "Filename" can have the extensions ".jpg" or ".bmp".  If no extension is specified, ".bmp" format (the preferred format for saving LTVT screen images) will be used.  

If the destination drive and folder are not explicity specified, they will be interpretted relative to the LTVT program folder (the folder containing the *.exe file).  

That is, filename = "test" is interpreted as a request to produce the file "test.bmp" in the LTVT program folder.

Filename = "ScriptImages\test" (or equivalently ".\ScriptImages\test" or ".\ScriptImages\test.bmp") places "test.bmp" in a (possibly new) subfolder called "ScriptImages" within the LTVT program folder (additional levels of subfolders can also be specified).  

Filename = "..\ScriptImages\test" places "test.bmp" in a (possibly new) subfolder called "ScriptImages" on the same level with the LTVT program folder.  

In all these cases if the script specifies a folder that does not already exist a message will be issued indicating the new folder has been created.  



== SAMPLE SCRIPT ==

Here is a simple script creating a time-lapse sequence of DEM simulations suitable for assembly into an animation:

* Generate and save image 1.bmp :
Date, 2010, 1, 1
Time, 0, 0, 0
ComputeGeometry
DEM
SaveImage, C:\LTVT Animation\1

* Generate and save image 2.bmp :
Time, 0, 15, 0
ComputeGeometry
DEM
SaveImage, C:\LTVT Animation\2

... (repeat)

In the first sequence, the first line sets the date.  The second sets the initial Universal Time on that date.  The third computes the observing geometry for that date and time (based on all other currently specified parameters, such as the observing location).  The fourth generates a DEM simulation on the screen, and the fifth saves the annotated screen image as "1.bmp" in the specified folder on the hard drive.

The command sequence is then repeated to produce a "2.bmp" representing the target 15 minutes later, and so on.  Supplementary software such as ImageJ can be used to assemble the saved screenshots into a GIF animation.

